



                       Winsock Interface Library

                               for C/C++

                                 (WIL4C)


                             USERS MANUAL



                               Version 1.0

                               July 28, 1997




                     This software is provided as-is.
              There are no warranties, expressed or implied.




                         Copyright (C) 1997
                           All rights reserved



                       MarshallSoft Computing, Inc.
                           Post Office Box 4543
                           Huntsville AL 35815

                           Voice : 205-881-4630
                             FAX : 205|880|0925
                             BBS : 205-880-9748
                           email : info@marshallsoft.com
                             web : www.marshallsoft.com

                               _______
                          ____|__     |                (R)
                       --+       |    +-------------------
                         |   ____|__  |  Association of
                         |  |       |_|  Shareware
                         |__|   o   |    Professionals
                       --+--+   |   +---------------------
                            |___|___|    MEMBER








     WIL4C Users Manual                                        Page 1

                            C O N T E N T S



        Chapter                                     Page


       1.0 Introduction................................................3
           1.1 User Support............................................4
           1.2 ASP Ombudsman...........................................4
           1.3 Installation............................................5
           1.4 Consulting Services.....................................5
       2.0 Library Organization........................................6
           2.1 Dynamic Link Libraries..................................6
           2.2 Using the Library.......................................6
           2.3 Compiling Programs......................................6
           2.4 Using a MAKEFILE........................................6
           2.5 Using an IDE............................................7
           2.6 Compiling WIL4C.........................................9
           2.7 Compiling Example Programs..............................9
       3.0 Internet Programming.......................................10
           3.1 Internet RFCs..........................................10
           3.2 Protocol Layers........................................11
           3.3 The Internet Protocol (IP).............................11
           3.4 Socket Concepts........................................12
           3.5 Client and Server Programming..........................14
           3.6 Stream (TCP) Programming...............................14
           3.7 Windows Winsock Programming............................14
           3.8 Synchronous VS Asynchronous Programming................15
           3.9 The ASYNC Functions....................................16
       4.0 Internet Protocols.........................................20
           4.1 Finger Protocol........................................20
           4.2 SMTP Protocol..........................................21
           4.3 POP3 Protocol..........................................23
           4.4 NNTP Protocol..........................................25
           4.5 FTP Protocol...........................................28
           4.6 HTTP Protocol..........................................31
       5.0 Problems...................................................33
       6.0 Example Programs...........................................34
           6.1 HOST...................................................34
           6.2 SFINGR, AFINGER, and FINGER............................34
           6.3 FROM...................................................34
           6.4 MAIL...................................................35
           6.5 FTP....................................................35
           6.6 NEWS...................................................36
           6.7 VIEW...................................................36
           6.8 WHO_C and WHO_S........................................37
           6.9 BCAST..................................................37
       7.0 Legal Issues...............................................38
           7.1 Registration...........................................38
           7.2 License................................................39
           7.3 Warranty...............................................39
       8.0 Summary....................................................40
           8.1 Revision History.......................................40
           8.2 WIL Function Summary...................................40
       9.0 Other MarshallSoft Computing Products......................42


     WIL4C Users Manual                                        Page 2

      1.0 Introduction

      The Winsock Interface Library for C/C++ (WIL4C) is a function library
      that simplifies Winsock programming and provides support for the most
      common Internet protocols such as DNS (Domain Name System), Finger,
      SMTP (Simple Mail Transport Protocol), POP3 (Post Office Protocol
      Version 3), FTP (File Transfer Protocol), NNTP (Network News
      Transport Protocol), and HTTP (Hypertext Transfer Protocol).

      Winsock network programming is not easy. Because of this, the primary
      purpose in designing WIL was to simplify Winsock programming.

      Winsock simplification is accomplished by:

      (1) Handling details like converting from host byte order to network
      byte order (and vice versa) as necessary automatically.

      (2) Handling the creation and manipulation of winsock data
      structures automatically.

      (3) Proving a straight forward interface, using only necessary
      arguments.

      (4) Providing more powerful functions, which may perform multiple
      Winsock functions.

      The WIL can be called from any program capable of calling Windows API
      functions, such as Delphi and Visual Basic.

      Support for the most common Internet protocols is provided by the
      ASYNC.C functions, which can transmit commands and receive responses
      formatted as used by these protocols.

      Lastly, a good selection of example programs are provided, covering
      the major Internet protocols. The example programs are designed to
      demonstrate how to use the WIL library functions. One of the best
      ways to learn Winsock programming is to study these examples.

      The shareware and registered versions are identical except for two
      differences: (1) the shareware version displays the "shareware"
      screen, and (2) the shareware version will "time out" after 20
      minutes, limiting execution to a maximum of twenty minutes EACH time
      a program is run. Of course, the registered version does not display
      the shareware screen nor time out after twenty minutes.

      We apologize for the inconvenience of the twenty minute timeout.
      Please contact us if more time is needed in order to evaluate WIL4C.











     WIL4C Users Manual                                        Page 3

      1.1 User Support

      We want you to be successful in developing your applications using
      WIL4C! We depend upon our customers to let us know what they need in
      a winsock communications library.  This means we are committed to
      providing the best library that we can. If you have any suggestions
      or comments, please let us know.

      If you are having a problem using WIL4C, call us at 205-881-4630
      between 1:30 PM and 9:30 PM CST Monday through Friday. You can also
      call at other times and leave a message, and call back later for a
      reply.

      However, we can only answer questions with respect to using the WIL4C
      library or our example programs.  We cannot help you program your
      application. See section 1.4 "Consulting Services".

      If you are on the Internet, email us at info@marshallsoft.com.  You
      can also get the latest versions of our products from our anonymous
      ftp site:

            FTP: ftp.marshallsoft.com      PATH: marshallsoft

      The MarshallSoft Computing, Inc. newsletter "Comm Talk" is published
      quarterly.  It discusses various communications problems and
      solutions using WIL4C as well as related information.

      The latest copy of our newsletter can be found on our anonymous ftp
      site (directory /marshallsoft/other) as well as our web site.

          Web site:  www.marshallsoft.com

      Our FTP site can also be accessed from our Web site.

      1.2 ASP Ombudsman

      MarshallSoft Computing, Inc.  is a member of the Association of
      Shareware Professionals (ASP).  ASP wants to make sure that the
      shareware principle works for you.  If you are unable to resolve a
      shareware-related problem with an ASP member by contacting the member
      directly, ASP may be able to help.  The ASP Ombudsman can help you
      resolve a dispute or problem with an ASP member, but does not provide
      technical support for members' products. Please write to the ASP
      Ombudsman at 545 Grover Road, Muskegon, MI USA 49442-9427, Fax
      616-788-2765, or send a CompuServe message via CompuServe Mail to ASP
      Ombudsman 70007,3536.












     WIL4C Users Manual                                        Page 4

      1.3 Installation

      (1) Before installation of WIL4C, your Windows C/C++ compiler should
      already be installed on your system and tested. In particular,
      include command line tools when installing your compiler.

      (2) Make a backup copy of your distribution disk.  Put your original
      distribution disk in a safe place.

      (3) Exit Windows into DOS, or start a DOS window:

      (4) Create your WIL project directory, copy the WIL archive, then
      unzip the archive. For example:

                MKDIR   WIL
                PKUNZIP WIL4C10.ZIP WIL

      (5) Use the provided install batch file (INSTALL) to install the
      library. The format is:

                INSTALL <compiler>

      where <compiler> must be "MS" for Microsoft,  "BC"  for  Borland,  or
      "WC" for Watcom. INSTALL performs the following copy operations:

      Microsoft:

         COPY WIL32M.LIB WIL32.LIB
         COPY WIL32M.DLL WIL32.DLL

      Borland:

         COPY WIL32B.LIB WIL32.LIB
         COPY WIL32B.DLL WIL32.DLL

      Watcom:

         COPY WIL32W.LIB WIL32.LIB
         COPY WIL32W.DLL WIL32.DLL

      WIL16.DLL is common for all of the supported compilers.

      1.4 Consulting Services

      We offer consulting services at $75 per hour, billed to your credit
      card in 10 minute increments. A work authorization letter must be
      signed and mailed or FAXed to us before we can start.

      Questions dealing with the use of our library or our example programs
      are covered as "support", for which there is no charge. Any other
      questions are considered consulting.







     WIL4C Users Manual                                        Page 5

      2.0 Library Overview

      2.1 Dynamic Link Libraries

      WIL4C includes both Win16 [WIL16] and a Win32 [WIL32] dynamic link
      library (DLL). A DLL is characterized by the fact that it need not be
      loaded until required by an application program and that only one
      copy of the DLL is necessary regardless of the number of application
      programs that use it. Contrast this to the traditional static library
      which is bound to each and every application that uses it at link
      time.

      Since WIL4C is a DLL, only one copy of the WIL4C code and data is
      loaded into memory regardless of the number of applications programs
      that use it. For example, more than one instance of the test program
      FINGER can be started.  All copies of FINGER can run concurrently.

      2.2 Using the Library

      The WIL4C has been tested on a Gateway 2000 (25 MHz 80386-DX, Windows
      3.1), a Gateway 2000 (66 MHz 80486-DX2, Windows 3.1), a Mid-West
      Micro (150 MHz Pentium, Windows 95), and a Toshiba Satellite (100 MHz
      Pentium, Windows 95).

      WIL4C has also been tested with Microsoft Visual C/C++, Borland C/C++
      (including C Builder), Turbo C/C++, and Watcom C/C++.

      2.3 Compiling Programs

      The example programs can be compiled by using either the provided
      makefiles or creating a project file for the IDE. Separate makefiles
      are provide for Win16 and Win32. 16-bit makefile end with "16" while
      32-bit makefiles end with "32".

      2.4 Using a MAKEFILE

      Makefiles originated on UNIX systems. They are the standard way that
      C/C++ programs are constructed in command line environments. Windows
      programs can be constructed with makefiles running DOS using command
      line Windows compilers.

      Makefiles are provided for Microsoft, Borland, and WATCOM command
      line compilers. Makefiles have file extensions of "_M_" for
      Microsoft, "_B_" for Borland, and "_W_" for WATCOM. Thus,
      FINGER16._W_ is the Watcom Win16 makefile for FINGER and FINGER32._M_
      is the Microsoft Win32 makefile.

      Turbo C/C++ for Windows and Borland C Builder do not support command
      line makefiles.

      Refer to MAKEFILE.TXT for more information on makefiles.







     WIL4C Users Manual                                        Page 6

      2.5 Using an IDE

      All current windows compilers have an Integrated Development
      Environment (IDE) for building application programs in the Windows
      environment. Since there is no standard format for IDE project files,
      file names must be entered into the IDE from the keyboard.  Each
      example program has a project text file (e.g. FINGER.PRJ) which
      contains the list of filenames that must be entered into the IDE.

      We do not distribute IDE files in our package because (1) they are
      very large, (2) they are not always upwardly compatible with previous
      versions of a particular IDE, (3) there is no standard project file
      format between compiler manufactures, and (4) they often must be
      modified to provide the correct path names.

      However, creating a project file within the IDE is very easy. Each
      application has a project file . Each project file contains the
      filenames that must be entered into the IDE.

      For each IDE, you will have to enter these filenames into the IDE.
      This is usually done with the INS key except for the Microsoft
      Developer, which uses menu commands. Be careful to enter all
      filenames as listed in the ".PRJ" file.

      All of the example application programs have been built using IDEs
      from Microsoft, Borland, and Watcom. However, there are differences
      between IDE versions from the same compiler manufacturer.

      All of the IDEs use the concept of a file hierarchy. For example, the
      Finger file hierarchy in the IDE (for 32-bit) should look like:

         FINGER.EXE
         |-- ABOUT.C
         |-- ASYNC.C
         |-- FINGER.C
         |-- FINGER.DEF
         |-- FINGER.RC
         |-- PAINT.C
         |-- STR.C
         |-- WIL32.LIB

      Replace WIL32.LIB above with WIL16.LIB for 16-bit applications. The
      order of the files is not significant.

      2.5.1 Microsoft IDE

      Choose "Project", then "New". Select Win16 [Win32] as the target. A
      dialog box will then pop up into which the project file names are
      entered.









     WIL4C Users Manual                                        Page 7

      2.5.2 Microsoft Developer

      Choose "File", then "New", then "Project Workspace". Select
      "Application" for "Type:" and your project name for "Name:". Choose
      Win16 or Win32 for platform. Then select "Create".

      Select "Insert", then "Files into Project". Add all filenames as
      listed in the ".PRJ" file corresponding to the project you are
      building. Lastly, select "Rebuild All".

      2.5.3 Borland IDE

      Turn off LINKER case sensitivities: Choose "Options", "Projects",
      "Linker", "General". Turn off the "case sensitive link" and "case
      sensitive exports and imports" boxes.

      Next, choose "Project", then "New Project". Use the INS (Insert) key
      to pop up a dialog box into which the project file names are entered.

      Select "GUI" for the "Target Model:" Only "Runtime" and "Dynamic"
      should be checked for "Standard Libraries:"

      NOTE1: If, after linking in the IDE, you get unresolved external
      references to the communications library functions in which each
      function name is all upper case, then you have NOT turned off case
      sensitivity as described above.

      NOTE2: If you get errors compiling the windows header file
      "WINDOWS.H", turn on "Borland Extensions" in "Options", "Project",
      "Compiler", "Source".

      2.5.4 Turbo C IDE

      Follow the same directions as above, except that the "Target Model:"
      can be any listed.

      2.5.5 Borland C Builder

      Choose "File" / "Open Project" on the menu bar. Load BCB_PRJ.MAK.
      Then, choose "Build All" from "Project" to create the executable.

      2.5.6 Watcom IDE

      Choose "File", then "New Project". Enter the project name and then
      choose Win16 [Win32] as the target. Use the INS (Insert) key to pop
      up a dialog box into which the project file names are entered.

      Select "Options" from the main window, then "C Compiler Switches",
      then "10". Memory Models and Processor Switches". Check "80386 Stack
      based calling [-3s]", then check "32-bit Flat model [-mf]".








     WIL4C Users Manual                                        Page 8

      2.6 Compiling WIL4C

      Precompiled DLL's are provided on disk for all the supported
      compilers. Registered users can recompile WIL.C in order to create
      WIL16.DLL and WIL32.DLL. Makefiles are provided for each compiler.

      For Microsoft C, type:

          NMAKE -f WIL16._M_
          NMAKE -f WIL32._M_

      For Borland C, type:

          MAKE -f WIL16._B_
          MAKE -f WIL32._B_

      For Watcom C, type:

          WMAKE -f WIL16._W_
          WMAKE -f WIL32._W_

      2.7 Compiling Example Programs

      There are makefiles provided for each of the example programs.
      For example, to compile FINGER:

      For Microsoft C, type:

          NMAKE -f FINGER16._M_
          NMAKE -f FINGER32._M_

      For Borland C, type:

          MAKE -f FINGER16._B_
          MAKE -f FINGER32._B_

      For Watcom C, type:

          WMAKE -f FINGER16._W_
          WMAKE -f FINGER32._W_

      WIL.C can also be recompiled within the IDE.
















     WIL4C Users Manual                                        Page 9

      3.0 Internet Network Programming

      It is assumed that the user of the WIL library is familiar with the
      Internet and programming, but not necessarily network programming.

      For more detailed information on the structure of the Internet, refer
      to one of the many excellent books on the subject. One of the best is
      Internetworking with TCP/IP, Volume I by Douglas E. Comer (Prentice
      Hall, ISBN 0-13-216987-8).

      One of the best ways to learn network programming is to study (and
      eventually modify) example code. For this reason, a good selection of
      program examples are provided.

      3.1 Internet RFCs

      The various Internet standards are defined in "Requests for
      Comments", or RFCs. RFCs are text files, and are available on the
      Internet at ftp://ds.internic.net. The index of all RFC documents is
      found in file rfc-index.txt.

      Some important RFCs include:

      RFC  791 : The Internet Protocol (IP)
      RFC  821 : Simple Mail Transport Protocol (SMTP).
      RFC  822 : SMTP Message Format.
      RFC  959 : File Transfer Protocol (FTP).
      RFC 1036 : Network News Transport Protocol (NNTP).
      RFC 1288 : The Finger protocol.
      RFC 1460 : Post Office Protocol, Version 3 (POP3).
      RFC 1521 : Multipurpose Extensions Mail Extensions (MIME).
      RFC 2068 : Hypertext Transfer Protocol 1.1 (HTTP).

      The above is just a sampling of the thousands of RFCs. Anyone wanting
      to implement a particular protocol should download a copy of the
      appropriate RFCs from the Internic.

      In addition to RFCs, the Internic also publishes additional classes
      of documents:

         (1) Internet Drafts (ID).
         (2) For Your Information (FYI).
         (3) Standard RFCs (STD).

      These documents are also found at ftp://ds.internic.net.













     WIL4C Users Manual                                        Page 10

      3.2 Protocol Layers

      The internet protocol layers look like:

         +---------------------+
         | Application Program |         FINGER.C, MAIL.C, FTP.C, ...
         +-+-----+-------------+
           |     |
           |   +-+-----------+
           |   | WIL Library |           WIL16.DLL and WIL32.DLL
           |   +-+-----------+
           |     |
         +-+-----+-----+
         | WINSOCK DLL |                 WINSOCK.DLL and WSOCK32.DLL
         +-------+-----+
                 |
                 +---------+
                 |         |
         +-------+--+  +---+------+
         | TCP code |  | UDP code |      (vendor specific)
         +--------+-+  ++---------+
                  |     |
                +-+-----+-+
                | IP code |
                +----+----+
                     |
             +-------+--------+
             | Network Driver |
             +-------+--------+
                     |
             +-------+--------+
             |   LAN or PPP   |
             +----------------+

      Each of the example programs uses the WIL (Winsock Interface Library)
      to simplify access to the WINSOCK.

      3.3 The Internet Protocol (IP)

      The Internet Protocol (IP) is the basis upon everthing else is built.
      It is documented in RFC 791.

      3.3.1 Best Effort Delivery

      Internet Protocol (IP) provides a "best effort" in delivering IP
      packets. Packets may arrive out of order, or may not arrive at all.
      The TCP (Transport Control Protocol) and UDP (User Datagram Protocol)
      are built on top of IP and perform additional error detection and
      correction.









     WIL4C Users Manual                                        Page 11

      3.3.2 IP Addresses

      Each host computer is assigned an unique 32-bit internet address that
      is used for all internet communications. Thus, if you dial up your
      Internet Service Provider (ISP), you are assigned an IP address owned
      by the ISP which is used to uniquely identify you while you are
      connected.

      The IP address is often written as four 8-bit decimal octets (bytes)
      separated by decimal points. For example, the 32-bit hexidecimal
      number 12AF7B02 can be written as

         18.175.123.2

      The internet standard for byte ordering within an integer is "Big
      Endian" (most significant byte first) and is denoted as the "network
      byte order". The host byte order depends on the particular computer
      architecture. For Intel based PCs, the host byte ordering is "Little
      Endian" (least significant byte first).

      The WINSOCK provides functions to convert between them. The Winsock
      Inteface Library (WIL) library always deals with addresses in host
      order, converting as necessary when communicating with the WINSOCK.

      3.4 Socket Concepts

      A socket is a small integer number used to identify the endpoint for
      TCP/IP communications. It is the fundamental Internet network
      programming interface.

      3.4.1 Socket Ports

      Internet communications occurs between two end-points each of which
      is defined by an IP address and a "port number", a 16-bit integer
      number. In this way, multiple sessions between the same two computers
      can occur simultaneously, each using a different port number.

      Established Internet Protocols have a port number called the "well
      known port" assigned to them. For example, FTP always uses port
      number 21.

      Application server programs should use a port number of at least
      5000. See the WHO_S program for an example server.

      Sockets are further differentiated as to whether they are TCP sockets
      or UDP sockets. WIL supports TCP sockets only.












     WIL4C Users Manual                                        Page 12

      3.4.2 Socket Address Structure

      The socket requires a socket address structure which contains
      additional information neccessary (port number, remote IP address,
      etc.) for communications to a remote endpoint.

      The WIL library handles all details of socket address structures.

      3.4.3 TCP and UDP Sockets

      There are two types of sockets: datagrams (UDP sockets) and streams
      (TCP sockets).

      UDP sockets are rarely used in network application programming, and
      are thus not implemented in WIL.

      TCP sockets implement bi-directional data streams, guaranteed to be
      error free. TCP is used for most application level net programming,
      including all of the example programs.

      3.5 Client and Server Side

      There are two distinct classes of internet programming: Client side
      and Server side.

      3.5.1 Server Programs

      A server is a program that provides some service. It runs
      continuously, waiting for a client to connect to it. Server programs
      listen for incoming connections. When an incoming connection is
      detected, the server program can accept the connection, after which
      the socket I/O can occur.


          +------+
          | BIND |
          +--+---+
             |
         +---+----+            +--------+
         | LISTEN +------------+ ACCEPT |
         +--------+            +--------+


      The program WHO_S is an example of a simple server program. It
      provides a simple "whois" service for its client WHO_C. Also see
      WHO_C, which is an example of a client for the WHO_S server.












     WIL4C Users Manual                                        Page 13

      3.5.2 Client Programs

      Most user application progams are "client side" programs. A client
      program is a program that connects to a server program to perform
      some service. A client program is run only when the service is
      needed.

      FINGER, VIEW, MAIL, FROM, FTP, NEWS, and WHO_C are all examples of
      client programs.

      3.6 Stream (TCP) Programming

      TCP (Transmission Control Protocol) is the basic protocol upon which
      all of the example programs are written. Some important
      characteristics of a TCP connection are:

      (1) The TCP connection as a bi-direction pipe, or stream. There is no
      concept of packets at the TCP level. What goes in one end comes out
      the other.

      (2) TCP provides for a reliable connection. Addition checksums are
      not required.

      (3) TCP uses a 16-bit port number to identify the connection
      endpoint. Thus, an "endpoint" is the pair (host, port). This allows a
      given host to be running multiple concurrent sessions, each with a
      unique endpoint.

      3.7 Windows Winsock Sockets

      There are really two classes of Winsock API calls: blocking and
      non-blocking (asynchronous). Sockets were originally designed for the
      UNIX operating system, and block until a requested operation
      completes. This works well in a true multi-tasked operating system
      like UNIX.

      When the Windows Winsock API was designed for Windows 3.X, several
      additional asynchronous winsock commands were added in addition to
      the traditional blocking commands.

      3.8 Synchronous Versus Asynchronous Programming

      There are two different styles of Winsock programming: Synchonous and
      Asychronous. Each has its advantages and disadvantages. WIL4C
      supports both styles of programming.

      Examples of the synchronous style include HOST, SFINGR, VIEW, WHO_S,
      and WHO_C.

      Example of the asynchronous style include AFINGR, FINGER, NNTP, MAIL,
      and FROM.

      FTP is an example employing both synchronous and asynchronous styles.





     WIL4C Users Manual                                        Page 14

      3.8.1 Synchronous Programming

      The synchronous style of Winsock programming is characterized by
      sending a command, then waiting for the response in a polling loop.
      Typically, the hour glass cursor is displayed during this waiting
      period. This style is typical of UNIX programs, but does not mesh
      well with the Windows message event loop, except for perhaps program
      threads running under Win32. On the positive side, synchronous
      programs are easier to follow and require less code.

      3.8.2 Asynchronous Programming

      The asynchronous style of Winsock programming is characterized by
      sending a command, then continuing on with other work until a message
      arrives signifying the completion of the command request. This style
      of Winsock programming uses the Windows message loop mechanism, and
      is considered the "Windows friendly" approach.

      Compare the three Finger programs SFINGR, AFINGR, and FINGER. SFINGR
      uses the synchronous style, AFINGR uses the asynchronous style, and
      FINGER uses the asynchronous style as implemented with the ASYNC.C
      module functions.

      Studying the three Finger programs (SFINGR, SFINGR, and FINGER) is a
      good way to compare the synchronous versus the two asynchronous
      styles of Winsock programming.

      Refer to the following section "The ASYNC Functions" for details on
      how the ASYNC functions operate. In particular, compare AFINGR (which
      does not use the ASYNC functions) to FINGER (which does).




























     WIL4C Users Manual                                        Page 15

      3.9 The ASYNC Functions

      The ASYNC functions operate using the wilAwaitEvent function to post
      winsock event messages to WM_USER, which are passed to the ASYNC code
      for processing. Messages may also be posted to WM_USER+1 to notify
      the application of the completion of a sequence of requested events.
      In practice, this is simpler than it sounds. Examine FINGER.C to see
      an example.

      The ASYNC functions are contained in the file ASYNC.C.

      3.9.1 AsyncConnect

      The purpose of the AsyncConnect function is to connect to a remote
      host.

      SOCKET AsyncConnect(
                   HWND hWnd,   /* window to post messages */
             LPSTR ServerType,  /* server type (eg: POP3) */
             LPSTR ServerName,  /* server name (eg: mail.iquest.com) */
                     int Port,  /* sever port */
               int SuccessMsg,  /* wParam for WM_MSG if successful */
               int FailureMsg)  /* wParam for WM_MSG if failure */

      In the following call to AsyncConnect, the caller is requesting a
      connection to a POP3 server with name "mail.iquest.com", using the
      well known POP3 port 110. If the connection is successful, message
      SUCCESS_MSG should be posted for event WM_USER+1 in window hWnd.
      If unsuccessful, FAILURE_MSG should be posted for event WM_USER+1.

      Socket = AsyncConnect(hMainWnd, "POP3", "mail.iquest.com",
                            110, SUCCESS_MSG, FAILURE_MSG);

      Upon success, the returned socket may be used for socket I/O.
























     WIL4C Users Manual                                        Page 16

      3.9.2 AsyncRead

      The purpose of the AsyncRead function is to wait for any incoming
      data on the port specified in the call to AsyncConnect.

      int AsyncRead(
               int SuccessMsg,  /* wParam for WM_MSG if successful */
               int FailureMsg,  /* wParam for WM_MSG if failure */
               int ReadType)    /* async read type */

      The ReadType can be any of the following:

         ReadType Symbol      Response Expected
         ASYNC_NONE             No server response is expected.
         ASYNC_SINGLE_LINE      Single Line of Text (LOT).
         ASYNC_MULTIPLE_LINES   Multiple LOTs.
         ASYNC_SINGLE_CODED     Single line: decimal response plus LOT.
         ASYNC_MULTIPLE_CODED   Multiple lines: decimal response plus LOT.
         ASYNC_PLUS_MINUS       Single line: "+OK" or "-ERR" plus LOT.

      The "Line of Text" (LOT) above consists of 7-bit ASCII characters
      followed by a carriage return (CR) and line feed (LF). The "decimal
      response" code consists of 3 decimal ASCII digits (eg: "125").

      In the following call to AsyncRead, the caller is awaiting a single
      line of test. Once the incoming text line is read and optionally
      echoed to the display (see AsyncSetEcho), message SUCCESS_MSG
      should be posted for event WM_USER+1. If unsuccessful, FAILURE_MSG
      should be posted for event WM_USER+1.

      AsyncRead = AsyncRead(SUCCESS_MSG, FAILURE_MSG, ASYNC_SINGLE_LINE);

      3.9.3 AsyncWrite

      The purpose of the AsyncWrite command is to write the specified
      command on the port specified in the call to AsyncConnect.

      int AsyncWrite(
                LPSTR Command,  /* command to send to server */
               int SuccessMsg,  /* wParam for WM_MSG if successful */
               int FailureMsg)  /* wParam for WM_MSG if failure */

      In the following call to AsyncWrite, the caller wants to write the
      text line in 'Command'. Once the text line is written and optionally
      echoed to the display (see AsyncSetEcho), message SUCCESS_MSG should
      be posted for event WM_USER+1. If unsuccessful, FAILURE_MSG should be
      posted for event WM_USER+1.

      AsyncRead = AsyncWrite("LIST", SUCCESS_MSG, FAILURE_MSG);









     WIL4C Users Manual                                        Page 17

      3.9.4 AsyncCommand

      The purpose of the AsyncCommand command is to combine the functions of
      AsyncWrite and AsyncRead into a single command.

      See AsyncWrite and AsyncRead above. Also refer to ther example
      programs which use AsyncCommand.

      int AsyncCommand(
                LPSTR Command,  /* command to send to server */
               int SuccessMsg,  /* wParam for WM_MSG if successful */
               int FailureMsg,  /* wParam for WM_MSG if failure    */
               int ReadType)    /* async read type */

      3.9.5 AsyncGetBufPtr

      The purpose of the AsyncGetBufPtr is to return a pointer to the text
      line buffer used by AsyncRead, AsyncWrite, and AsyncCommand.

      LPSTR AsyncGetBufPtr(void);

      3.9.6 AsyncProcessMsg

      The purpose of the AsyncProcessMsg command is to process WM_USER
      messages. The main window (as specified by hWnd in the call to
      AsyncConnect) should contain the following line in the main event
      loop:

         case WM_USER:
           AsyncProcessMsg(wParam)
           break;

      The application should NOT post WM_USER messages when using the ASYNC
      functions.

      3.9.7 AsyncSetEcho

      The purpose of the AsyncSetEcho function is to set the echo flag for
      all subsequent ASYNC processing.

         int AsyncSetEcho(int EchoFlag);

      If the EchoFlag is TRUE, all text strings sent to (and received from)
      the server are echoed to the display. The AsyncSetEcho function
      returns the previous value of the echo flag.













     WIL4C Users Manual                                        Page 18

      3.9.8 AsyncSetDebug

      The purpose of the AsyncSetDebug function is to set the debug flag.
      The DebugFlag is used by the ASYNC code to display additional
      information. The AsyncSetDebug flag is meant for debugging ASYNC
      calls.

         int AsyncSetDebug(int DebugFlag);

      The programmer should rarely have need to use this function.

      3.9.9 POST Macros

      Posting to WM_USER is reserved for ASYNC functions. Posting to
      WM_USER+1 may be done by both ASYNC finctions and application
      functions.

      Two macros are defined for posting messages to WM_USER+1. The
      POST_MSG macro posts message (m) with parameter value 0. The
      POST_PARM macro posts message (m) with parameter (p).

      The POST_PARM macro is used pass back the numeric 3-digit response
      codes from SMTP, FTP, etc., or the "+OK" (100) or "-ERR" (500) POP3
      codes.

      The macros are defined in ASYNC.H as

         #define POST_MSG(m) PostMessage(hMainWnd,WM_USER+1,(m),0)

         #define POST_PARM(m,p) PostMessage(hMainWnd,WM_USER+1,(m),(p))

      The POST macros are used by both the ASYNC functions and the example
      code.

























     WIL4C Users Manual                                        Page 19

      4.0 Internet Protocols

      The Internet protocols to follow all communicate using ASCII text
      lines. Each line ends with a carriage return, line feed (CR, LF)
      pair. The client program initiates the protocol by connecting to the
      server. What happens next is dependent on the particular protocol.

      The following discussions are for overview only. Refer to the proper
      RFCs for details on the protocols.

      4.1 Finger

      The Finger protocol is one of the simplest Internet protocols. For
      this reason, it is an excellent protocol to study for those without
      any Winsock programming experience.

      Finger allows one to retrieve information about a remote user on a
      remote host machine. If the remote user has a "plan file", then this
      information is returned in addition to the normal Finger data.

      Finger uses TCP with well known port number 79.

      The client side of the Finger protocol works as follows:

      (1) The client connects to the Finger sever on the remote host using
      TCP and port 79. The server does NOT send a greeting.

      (2) Once connected, the client sends a single line of text containing
      the login name of the user for which information is wanted.

      (3) The Finger server will send a series of text lines back. After
      the last line, the Finger server closes the connection.

      The Finger protocol is a very simple protocol. Three example Finger
      programs are included:

      (1) SFINGR: Synchronous version of Finger.
      (2) AFINGR: Asynchronous version of Finger.
      (3) FINGER: Asynchronous version of Finger using the ASYNC functions.

      Also see RFC 1288 for a detailed description of Finger.

      Note that not all Internet hosts provide Finger servers, although
      many do.














     WIL4C Users Manual                                        Page 20

      4.2 SMTP

      The SMTP (Simple Mail Transport Protocol) protocol allows the user to
      send mail to a remote user. SMTP uses TCP with well known port number
      25. All mail messages must consist of one or more lines of 7-bit
      ASCII characters, each line terminating with a carriage return, line
      feed pair.

      All server responses begin with a 3 digit decimal response code.
      Values of 500 and above indicate an error condition.

      4.2.1 SMTP Protocol

      The client side of the SMTP protocol works as follows:

      (1) The client connects to the SMTP server on the remote host using
      well known port 25. Once connected, the server responds with a
      greeting message, which may be one or more lines.

      (2) The client sends the "HELO myhost.com" command to the server
      where myhost.com is the local host name. The server responds with a
      greeting message.

      (3) The client sends the "MAIL FROM" command as shown in the example
      below. The server should respond with "250 OK".

      (4) The client sends the "RCPT TO" command to identify the recipient
      of the mail. The server responds with "250 OK". Additional recipients
      are sent by the client as required by sending additional "RCPT TO"
      commands.

      (5) The client sends the "DATA" command as shown below. The server
      responds with "250 OK".

      (6) The client sends the mail message as a series of text lines, each
      terminated by a carriage return, line feed pair. A text line
      consisting of just a period is "quoted" by adding a second period,
      since a line with a lone period indicates the end of the message.

      After all message lines have been sent, a line with a lone period
      (".\r\n") is sent to end the transmission. The server responds with
      "250 OK".

      (7) If another email is to be send, go back to step (4) above,
      otherwise sign off by sending the "QUIT" command.













     WIL4C Users Manual                                        Page 21

      4.2.2 SMTP Example

      In the following example, the caller mike@marshallsoft.com sends a 3
      line email message to Pierre at pierre@louve.com. Each line sent and
      received terminates with a carriage return, line feed pair. The "C:"
      (for client) and "S:" (for server) are not part of the protocol, but
      are shown to identify the client (C:) and server (S:) originated
      messages.

      C: (Connects to remote SMTP server).
      S: 220 LOUVE.COM SMTP server version 1.2.1
      C: HELO marshallsoft.com
      S: 250 Nice to meet you marshallsoft.com
      C: MAIL FROM:<mike@marshallsoft.com>
      S: 250 OK
      C: RCPT TO:<pierre@louve.com>
      S: 250 OK
      C: DATA
      S: 250 OK
      C: first line of email
      C: second line of email
      C: third line of email
      C: .
      S: 250 OK
      C: QUIT
      S: 221 au revoir.

      Refer to the MAIL and BCAST programs for examples of a SMTP client.

      Also see RFC 821 for a complete description of SMTP.




























     WIL4C Users Manual                                        Page 22

      4.3 POP3

      The POP3 (Post Office Protocol version 3) protocol allows the user to
      retrieve mail from his POP3 server. POP3 uses TCP with well known port
      number 110.

      All server responses consists of a single line of text ending with a
      carriage return, line feed pair and beginning with either a "+OK" or
      "-ERR".

      4.3.1 POP3 Protocol

      The client side of the POP3 protocol works as follows:

      (1) The client connects to the POP3 sever on the remote host using
      TCP and port 110.  The server responds with its greeting.

      (2) The client sends the USER command to identify the account. The
      server responds with "+OK".

      (3) The client sends the password for the USER account using the PASS
      command. The server responds with a "+OK".

      (4) The client is now "logged onto" the POP3 server. Several commands
      can now be sent including:

        (a) The STAT command request the # of messages (and total bytes)
            waiting.

        (b) The RETR command retrieves a particular message number.

        (c) The DELE command deletes a particular message number

      Refer to the following example for the usage of these commands.

      (5) After all processing is done, the QUIT command is sent to log off
      of the POP3 server. The server responds with "+OK".

      Note that you must have a POP3 account set up by the host computer's
      system administrator. Mail sent to you is queued on your POP3 account
      for retrieval by you.

















     WIL4C Users Manual                                        Page 23

      4.3.2 POP3 Example

      In the following example, Pierre has a POP3 account set up with user
      name "Pierre" and password "francaise". The client program connects
      to the POP3 server, gets the message status, receives the first
      message, and then deletes it.

      C: (Connects to remote POP3 server).
      S: +OK server SuperPOP ready.
      C: USER Pierre
      S: +OK user is Pierre
      C: PASS francaise
      S: +OK Pierre's maildrop has 2 messages.
      C: STAT
      S: +OK 2 1950
      C: RETR 1
      S: +OK 1050 bytes
      S: (1st line of email message 1)
      S: (2nd line of email message 1)
      :
      S: (last line of email message 1)
      S: .
      C: DELE 1
      S: +OK message 1 deleted
      C: QUIT
      S: +OK goodbye.

      Refer to the FROM and MAIL programs for examples of a POP3 client.

      Also see RFC 1460 for a complete description of SMTP.




























     WIL4C Users Manual                                        Page 24

      4.4 NNTP

      The NNTP (Network News Transport Protocol) protocol allows the
      client to download (and upload) network news articles from his NNTP
      server. NNTP uses TCP with well known port number 119.

      The client sends text command lines to the server, and the server
      responds with a 3 digit numeric coded response line plus the
      requested text information. If text information is sent by the
      server, the last line will consist of (a text line with) a single
      period. Server response codes of 500 and above indicate an error
      condition.

      The NTTP news server maintains a list of news articles grouped into
      sets called "newsgroups", each of which has a name. The LIST command
      can be used to read all newsgroups. A particular newgroup must be
      selected by the GROUP command before any news articles can be read.

      Each newsgroup consists of zero or more articles. Individual articles
      are numbered and are deleted by the server after some period of time
      after first receiving the article, depending on the individual
      server. The article number of deleted articles are not reused.

      Each article consists of two parts: the article header and the
      article body. The article header consists of a short summary of the
      article body itself. The server maintains a "current pointer" to the
      current article, initialized to the first article in the newsgroup.

      Once a newsgroup has been selected, news headers and/or articles can
      be read. Commands include:

         HEAD        : read the current article header.
         HEAD ddd    : read article header number ddd (eg: READ 1286).
         ARTICLE     : read the current article.
         ARTICLE ddd : read article number ddd.
         NEXT        : advance to next article in the newsgroup.
         LAST        : advance to last article in the newsgroup.

      Articles can also be posted by the NTTP client by using the POST
      command, if allowed for the particular newsgroup.


















     WIL4C Users Manual                                        Page 25

      4.4.1 NNTP Protocol

      The client side of the NNTP protocol works as follows:

      (1) The client connects to the NNTP sever on the host (typically your
      ISP) using TCP and port 119. The server responds with its greeting
      message.

      (2) The client may send a LIST command to request a list of
      newsgroups. The server responds with a (usually very long) list of
      newsgroups.

      (3) The client selects a newsgroup using the GROUP command. The
      server responds with a response line consisting of the response code,
      the number of articles, the first article number, the last article
      number, and the group selected. For example

         211 1982 18726 21918 comp.lang.c

      (4) The client requests article headers by using the HEADER command
      and the article body itself by using the ARTICLE command. The client
      may also advance the current article pointer by using the NEXT or
      LAST command. Note that the NEXT and LAST command do not retrieve a
      article header or the article body itself, but rather just move the
      current article pointer so that subsequent HEADER or ARTICLE commands
      (without a specified article number argument) will retrieve the
      current article header or article body.

      (5) The client can post articles, if allowed, by using the POST
      command. After sending the POST command (without any arguments), the
      server will prompt you to send the body of the article to be posted,
      which consists of multiple text lines, followed by a line with just a
      period.

      Refer to RFC 1036 for details on article formats.























     WIL4C Users Manual                                        Page 26

      4.4.2 NNTP Example

      In the following NNTP session, the client connects to the NTTP
      server, request a list of all newsgroups, selects newsgroup
      comp.lang.c, request the current (first) article, request the last
      article, then quits.

      C: (Connects to NTTP server using TCP on port 119).
      S: SuperNTTP ready. Posting OK.
      C: LIST
      S: comp.protocols.tcp-ip 514 819 Y
      S: comp.lang.c 1182 1271
      :
      S: .
      C: GROUP comp.lang.c
      S: 211 1982 18726 21918 comp.lang.c
      C: ARTICLE
      S: 1st line of current article (#18726)
      S: 2nd line of current article (#18726)
      :
      S: last line of current article (#18726)
      S: .
      C: LAST
      S: Article 21918 selected. Use ARTICLE to retrieve article.
      C: ARTICLE
      S: 1st line of current article (#21918)
      S: 2nd line of current article (#21918)
      :
      S: last line of current article (#21918)
      S: .
      C: QUIT

      Refer to the NEWS program for an example of a NNTP client. Note that
      the example program NEWS does not support article posting.

      Refer to RFC 1036 for a complete description of NNTP.






















     WIL4C Users Manual                                        Page 27

      4.5 FTP

      The FTP (File Transfer Protocol) protocol allows the user to upload
      and download text and binary files. FTP uses TCP with well known port
      number 21.

      Two types of FTP service exists. The first is where the client
      connects to a remote host for which he knows the password, allowing
      him both read and write access.

      The second type of FTP service is called "anonymous FTP" in which the
      USER name is "anonymous" ("ftp" is sometimers acceptable instead of
      "anonymous") with the password set to the clients' email address.
      This type of FTP service is very common on the Internet. Examples
      include the MarshallSoft Computing anonymous FTP site at
      "ftp.marshallsoft.com".

      The FTP server responds to client commands with a 3 digit number
      response code followed by the text of the repsonse message, and
      ending with a carriage return, line feed pair. Response codes of 500
      and above indicate a fatal error condition, 400 to 499 indicate a
      recoverable error condition (try the command again), while codes of
      100 through 399 indicate that all went OK. Refer to RFC 959 for more
      details on FTP response codes.

      The FTP server may respond with a multi-line response. A dash after
      the response code indicates that this is not the last response line.

         100-1st line of response.
         100-2nd line of response.
         100 last line of response.

      Occassionally, other response codes are sent before the last response
      line, which must always have the same response code as the first
      response line. For example,

         100-1st line of response for code 100.
         101 1st line ine of response for code 101.
         100 last line of response.

      FTP does not use the port on which it connects (the control port) to
      transfer data. Rather, the FTP specifies (using the control port)
      which port to establish a data connection on using the PORT command
      (see below). The FTP client then listens on this port for a
      connection, after which data can be transferred. After all data is
      transferred, the data port is closed.












     WIL4C Users Manual                                        Page 28

      4.5.1 FTP Protocol

      The FTP protocol works as follows:

      (1) The client connects to the FTP sever on the remote host using TCP
      and port 21. The server responds with its greeting.

      (2) The client sends the USER command to identify the account. The
      server responds with response code 331.

      (3) The client sends the password for the USER account using the PASS
      command. The server responds with response code 230.

      (4) The client is now "logged onto" the FTP server. Several commands
      can now be sent including:

        (a) The CWD command changes the working directory on the remote
            machine. If you connect to ftp.marshallsoft.com, you should
            use the CWD command to change the working directory to
            "marshallsoft".

        (b) The LIST command lists all the files in the directory on the
            remote computer. The LIST command does a formatted list, while
            the NLST command just lists the filenames. The LIST (and NLST)
            command requires that the PORT command (see below) be issued
            first to establish the data port.

       (c)  The TYPE command is used to set either ASCII (TYPE A) or binary
            mode (TYPE I) to be used for subsequent file transfers. The
            default is ASCII. The ASCII and BINARY menu commands in the
            example program FTP.C issue the FTP TYPE command.

            The TYPE command should be used to set binary mode (see the
            example program FTP.C) before transfering binary files.

       (f)  The PORT command is used to specify the port over which data
            will be transferred. The PORT command must be used before using
            the LIST, NLST, RETR or STOR command. For example, to specify
            data port 6146 (256*24 + 2) using our (not the remote
            machines) IP address of 165.113.131.70, we use

                PORT 165,113,131,70,24,2

        (e) The RETR command is used to download a file from the remote
            computer, using the type as set by the TYPE command, and the
            data port specified by the PORT command. The data port is
            closed immediately after all data is tranferred.

        (f) The STOR command is used to upload a file to the remote
            computer, using the type as set by the TYPE command, and the
            data port specified by the PORT command. The data port is
            closed immediately after all data is tranferred.

            Note that most anonymous FTP sites do not allow uploading.

        (g) The QUIT command logs off of the FTP server.


     WIL4C Users Manual                                        Page 29

      4.5.2 FTP Example

      In the following FTP session, Pierre connects to a FTP server as
      anonymous, lists all files, changes current directory to
      "marshallsoft/other", sets binary file type, downloads file
      DISKBK11.ZIP, then logs off.

      C: (Connects to remote FTP server).
      S: 220 SuperFTP server is ready.
      C: USER anonymous
      S: 331 Use email address for password.
      C: PASS pierre@louve.com
      S: 230-User Pierre logged on.
      S: 230 This site allows read access only!
      C: LIST
      S: (1st line of directory listing)
      S: (2nd line of directory listing)
      :
      S: (last line of directory listing)
      S: .
      C: CWD marshallsoft/other
      S: 250 CWD command successful.
      C: TYPE I
      S: 200 Type is set to I.
      C: PORT 11,231,11,14,20,15
      S: 200 Port command successful.
      C: GET diskbk11.zip
      S: 150 Opening BINARY mode data connection for diskbk11.zip
         (file comes in on data port, after which is is closed).
      S: 226 Transfer complete.
      C: QUIT
      S: Au revoir Pierre!

      Refer to the FTP program for an example of a FTP client.

      Refer to RFC 959 for a complete description of FTP.






















     WIL4C Users Manual                                        Page 30

      4.6 HTTP

      The HTTP (Hyper Text Transfer Protocol) protocol defines the
      interation between World-Wide-Web (WWW) servers and WWW clients,
      popularly known as "Web Browsers".

      HTTP uses TCP with well known port number 80, and is documented in
      RFC 2068.

      HTTP is a complicated protocol. RFC 2068 describing HTTP/1.1 is 162
      pages in length. If you want to develop a web browser, you must get a
      copy of RFC 2068 from the Internic.

      You will also need to have a knowledge of HTML (Hypertext Markup
      Language) in order to interprete the data sent by the HTTP server.
      Fortunately, there are several very good books on HTML such as "Teach
      Yourself Web Publishing with HTML in 14 Days" by Laura LeMay (Sams
      Net).

      A very good way to get comfortable with HTML is to build your own WEB
      site. Most ISPs (Intenet Service Providers) make provisions for their
      customers to build "personal" web sites.

      With some practical experience "surfing the web", a knowledge of
      HTML, RFC2068, and the example program VIEW.C, you are ready to write
      a HTTP application.

      4.6.1 HTTP Protocol

      HTTP commands are termed "Methods". These commands are case-sensitive
      and include only two required (for all HTTP servers) commands: GET
      and HEAD.

      The GET command is the fundamental command which retrieves HTML
      pages. For example,

         GET /index.html HTTP/1.0

      requests page INDEX.HTML.

      The HEAD method is identical to GET except that only "meta"
      information is returned for the page.

      The HTTP client connects to the HTTP server on the remote host, sends
      a command, receives a response, then terminates the connection. This
      is repeated for each HTTP command.

      The server response consists of header text, followed by a blank
      line, followed by the actual HTML page requested. The first line of
      the header text consists of the status return, such as:

         HTTP/1.0 200 OK

      Return value of 500 & above are server errors, and 400 to 499 are
      client errors.



     WIL4C Users Manual                                        Page 31

      4.6.2 HTTP Example

      Suppose that the following Web page HELLO.HTM is on the MarshallSoft
      Web site (www.marshallsoft.com).

         <HTML> <HEAD>
         <TITLE> MarshallSoft Computing, Inc. </TITLE>
         </HEAD>
         <H1> Hello </H1>
         Hello, world!
         </BODY> </HTML>

      The following exchange with the HTTP server on the host requests the
      page HELLO.HTM.

      C: (Connects to remote FTP server).
      C: GET /index.html HTTP/1.0
      S: HTTP/1.0 200 OK
      S: Date: Wed, 09 Jul 1997 20:43:59 GMT
      S: Server: Apache/1.1.3
      S: Content-type: text/html
      S: Content-length: 183
      S: Last modified: Wed, 09 Jul 1997 20:00:01 GMT
      S:
      S: <HTML> <HEAD>
      S: <TITLE> MarshallSoft Computing, Inc. </TITLE>
      S: </HEAD>
      S: <H1> Hello </H1>
      S: Hello, world!
      S: </BODY> </HTML>
      C: (Disconnects)

      It is up to the HTTP client to interpret the HTML lines, for which
      knowledege of the HTML specification is necessary.

      Note that the client disconnects after receiving each page.






















     WIL4C Users Manual                                        Page 32

      5.0 Problems

      Before attempting to run any of the example programs, you should
      already be able to connect to the Internet and run your email client
      program, such as Eudora or Pegasus Mail. You should also be
      comfortable as a user of the Internet before attempting to program
      Internet applications.

      If you cannot get your application to run properly, first compile and
      run the example programs. If you call us to report a possible bug in
      the library, the first thing we will ask is if the example programs
      run correctly.

      If you are having trouble with a particular protocol, download the
      RFCs from the Internic for detailed protocol information. Also
      experiment with the appropriate example program. Unfortunately, there
      is no substitute for trail and error! Another good resource are the
      many books and magazines articles around dealing with the various
      Internet protocols.

      Although we will be happy to talk to you, we are not experts on the
      Internet protocols. Our support is limited to the use of our library,
      not the operation of the Internet protocols.

      If your application does not run but the example applications run
      correctly, then you have most likely made a programming mistake in
      your application. MarshallSoft Computing cannot debug your
      application, especially over the telephone!

      We recommend the following steps if you believe that you have
      discovered a bug in the library: (1) Create the smallest, simplest
      test program possible that demonstrates the problem.  (2) Document
      your exact machine configuration and what error the test program
      demonstrates. (3) Email your program to us at bugs@marshallsoft.com.

      If the problem can be solved with an easy work-around, we will
      publish the work-around.  If the problem requires a modification to
      the library, we will make the change and make the modified library
      available to our customers without charge.



















     WIL4C Users Manual                                        Page 33

      6.0 Example Programs

      There are 12 example programs, covering DNS, Finger, SMTP, POP3,
      NNTP, FTP, and HTTP.

      6.1 HOST

      The HOST program uses the Domain Name System (DNS) to get internet
      addresses for hosts for which their name is known. HOST can also get
      port and server information, if available.

      6.2 SFINGR, AFINGR, and FINGER

      The three finger programs demonstrate the 3 methods of using the
      WIL4C library. The FINGER protocol is presented in the section on
      protocols.

      SFINGR make only synchronous function calls. Refer to the section on
      "Synchronous WIL" for information on synchronous calls.

      AFINGR make asynchronous function calls. Refer to the section on
      "Asynchronous WIL" for information on aynchronous calls.

      FINGER make asynchronous function calls using the ASYNC commands.
      Refer to "Using ASYNC Functions" for more information.

      The Finger client program contact your Finger Server and requests
      information for a particular user. Many hosts do not have finger
      servers.

      You can finger MarshallSoft Computing by specifying (at the prompt)
      "msc@advicom.com".

      6.3 FROM

      The FROM client program logs onto your POP3 account and checks if
      you having any waiting mail. If you do, it list the messages by
      number along with the "From:" and "Subject:" fields, if any.

      In order to use FROM, you must edit the file FROM.INI which contains
      POP3 server addresses, and login name & password.

      For example, suppose your ISP (Internet Service Provider) has host
      address SUPERSERVE.COM, and your login name is billy. Then FROM.INI
      may contain:

         +---------------------------+
         | POP3=mail.superserve.com  |
         | USER=billy                |
         | PASS=my_password          |
         +---------------------------+







     WIL4C Users Manual                                        Page 34

      6.4 MAIL

      The mail client program is similiar to FROM, except that it can also
      send, receive, and delete mail.

      In order to use MAIL, you must edit the file MAIL.INI which contains
      SMTP & POP3 server addresses, and login name & password.

         +---------------------------+
         | SMTP=mail.superserve.com  |
         | POP3=mail.superserve.com  |
         | USER=billy                |
         | FROM=billy@superserve.com |
         | PASS=my_password          |
         +---------------------------+

      MAIL.INI is similiar to FROM.INI with the addition of the SMTP server
      (for sending mail) and your email address (FROM line). In fact, you
      can also use MAIL.INI for FROM.INI.

      See section 6.9 (BCAST) for a description of the file format for
      outgoing email messages. Note that the first line must be the
      destination email address.

      6.5 FTP

      The FTP (File Transfer Protocol) client program communicats with a
      FTP server, allowing for the transfer of ASCII and binary files.
      Refer to the section on protocols for information on the FTP
      protocol.

      You must provide the login name and password in FTP.INI. For example,
      if your email address is billy@superserve.com, FTP.INI would contain
      the following for anonymous FTP.

         +---------------------------+
         | USER=anonymous            |
         | PASS=billy@superserve.com |
         +---------------------------+

      The FTP client program is capable of the following operations:

      Command  Description
          CWD  Changes the working directory at the host.
         LIST  List the contents of the current working directory.
        ASCII  Set ASCII transfer mode.
       BINARY  Sets binary transfer mode.
          GET  Receives specified file from the host.
          PUT  Sends specified file to the host.
         QUIT  Quits the FTP session.

      Don't forget to set BINARY mode before downloading or uploading a
      binary file.





     WIL4C Users Manual                                        Page 35

      6.6 NEWS

      The NEWS client program communicates with a NNTP (Network News
      Transport Protocol) and provides the following functions:

      Command           Description
      Group/
        List            List all groups.
        Select          Select a group for subsequent processing.
      Header/
        GetByNumber     Selects header by number.
        GetCurrent      Selects current header.
        Next            Selects next header.
        Last            Select last header.
      Article/
        GetByNumber     Selects article by number.
        GetCurrent      Selects current article.
        Next            Selects next article.
        Last            Select last article.
      Quit              Quits the NEWS server.

      If the user specifies "Group/List", the incoming list of groups is
      saved in the file NEWS.LST. If the user requests an article by number
      "Article/GetByNumber", then the article is saved with file extension
      ".ART".

      Refer to the section "NNTP Protocol" for information on NNTP.

      6.7 VIEW

      VIEW is HTTP client program which requests and displays source code
      for a specified HTTP web page. VIEW is not a browser!

      VIEW can be used as the basis for several types of HTTP clients. Some
      ideas are as follows:

      (1) VIEW can be used as the starting point for a web browser. Most of
      the effort will be in writing the code necessary to interpret the
      HTML (Hypertext Markup Language) text.

      (2) VIEW could also be used as the basis for a "ROBOT" program, that
      searches for email addresses. This is what some search engines do in
      order to catalog the web sites on the Internet.

      (3) VIEW could also be used as the starting point for a program that
      connects to a search engine, copying search results for subsequent
      anyalyis.

      VIEW uses the synchronous style of programming.









     WIL4C Users Manual                                        Page 36

      6.8 WHO_C and WHO_S

      WHO_S is a server program which provides "WHOIS" service for three
      individuals as requested by the client WHOIS program WHO_C.

      After starting the server WHO_S, note the IP address. Next, start the
      client WHO_C, using the WHO_S server IP address to specify the server.

      Then, specify one of the three people in the WHOIS database: Mike,
      Pam, or Lauren.

      The purpose of the WHOIS programs is to demonstate how to write a
      simple Internet server and matching client.

      6.9 BCAST

      BCAST is a SMTP client that emails a file to each address specified
      in a list, such as emailing our newsletter to our customers.

      Several pieces of information must be in the BCAST.INI file:

      +-------------------------------+
      | SMTP=your_SMTP_server_address |
      | FROM=your_email_address       |
      | RCPT=file_of_email_addresses  |
      | MAIL=file_to_email            |
      +-------------------------------+

      Outgoing email messages should be ASCII text files formatted as:

      Line 1: Email address of destination (MAIL program only).
      Line 2: "To: " header line.
      Line 3: "From: " header line.
      Line 4: "Subject: " header line.
      Line 5: Blank line.
      Line 6 to last_line: ASCII email message.

      Example outgoing email message:

      +-----------------------------------------------------+
      |mike@marshallsoft.com                                |
      |To: mike@marshallsoft                                |
      |From: pam@traveller.com                              |
      |Subject: Test message                                |
      |                                                     |
      |The mail destination address must be the 1st line for|
      |email being sent with the MAIL example program. The  |
      |"To:", "From:", and "Subject:" fields are optional.  |
      |There should be a blank line before the body of the  |
      |message. [7/25/97].                                  |
      +-----------------------------------------------------+







     WIL4C Users Manual                                        Page 37

      7.0 Legal Issues

      7.1 Registration


      WIL4C may be registered for $95 plus $6 S&H ($12 outside of North
      America).

      To order, contact us as shown on the title page of this manual. All
      prices are guaranteed for one year from the release date.

      Multiple copy discounts (3 or more) and site licenses are available.
      Please call for details.

      We  accept American Express, VISA, MasterCard, Discover, checks in US
      dollars drawn on  a  US  bank,  International  Postal  Money  Orders,
      purchase orders (POs) from recognized US schools and companies listed
      in  Dun  &  Bradstreet,  and  COD  (street  address  and phone number
      required) within the USA (plus a $5 COD charge).

      For credit card orders, be sure to include the account number, the
      expiration date, the exact name on the card, and the complete card
      billing address (the address to which the credit card bill is
      mailed).

      Print the file INVOICE.TXT if a "Pro Forma" invoice is needed.

      If you wish to update from an older version of WIL4C, send $25 plus
      $6 S&H ($12 S&H outside of North America).

      The registered package includes:

           o  Win16 & Win32 WIL4C Libraries w/o shareware screens.
           o  Win16 & Win32 source code for WIL and ASYNC.
           o  Printed Users Manual & Reference Manual.
           o  Telephone and email support for one year.

      The registered user will receive the latest version of WIL4C shipped
      by US second day priority mail (packet airmail overseas).  A 3.5"
      HD diskette is provided.


















     WIL4C Users Manual                                        Page 38

      7.2 License

      MarshallSoft Computing, Inc. grants the registered user of WIL4C the
      right to use one copy of the WIL4C library (in object form) on a
      single computer in the development of any software product (other
      more than one computer at the same time.  The source code for the
      library (WIL.C and ASYNC.C) is copyrighted by MarshallSoft Computing
      and may not be released in whole or in part. Products developed using
      WIL4C may be distributed without royalty.

      7.3 Warranty

      MARSHALLSOFT COMPUTING, INC.  DISCLAIMS ALL WARRANTIES RELATING TO
      THIS SOFTWARE, WHETHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT
      LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
      A PARTICULAR PURPOSE, AND ALL SUCH WARRANTIES ARE EXPRESSLY AND
      SPECIFICALLY DISCLAIMED. NEITHER MARSHALLSOFT COMPUTING, INC.  NOR
      ANYONE ELSE WHO HAS BEEN INVOLVED IN THE CREATION, PRODUCTION, OR
      DELIVERY OF THIS SOFTWARE SHALL BE LIABLE FOR ANY INDIRECT,
      CONSEQUENTIAL, OR INCIDENTAL DAMAGES ARISING OUT OF THE USE OR
      INABILITY TO USE SUCH SOFTWARE EVEN IF MARSHALLSOFT COMPUTING, INC.
      HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR CLAIMS. IN NO
      EVENT SHALL MARSHALLSOFT COMPUTING, INC.'S LIABILITY FOR ANY SUCH
      DAMAGES EVER EXCEED THE PRICE PAID FOR THE LICENSE TO USE THE
      SOFTWARE, REGARDLESS OF THE FORM OF THE CLAIM. THE PERSON USING THE
      SOFTWARE BEARS ALL RISK AS TO THE QUALITY AND PERFORMANCE OF THE
      SOFTWARE.

      Some states do not allow the exclusion of the limit of liability for
      consequential or incidental damages, so the above limitation may not
      apply to you.

      This agreement shall be governed by the laws of the State of Alabama
      and shall inure to the benefit of MarshallSoft Computing, Inc.  and
      any successors, administrators, heirs and assigns.  Any action or
      proceeding brought by either party against the other arising out of
      or related to this agreement shall be brought only in a STATE or
      FEDERAL COURT of competent jurisdiction located in Madison County,
      Alabama. The parties hereby consent to in personam jurisdiction of
      said courts.


















     WIL4C Users Manual                                        Page 39

      8.0 Summary

      8.1 Revision History

      Version 1.0: 28 July, 1997.

          o  The initial release of WIL4C.






      [reserved]







      8.2 WIL4C Function Summary

      Refer to the WIL4C Reference Manual (WIL4C_R.TXT) for detailed
      information on the communications and support functions.  A one line
      summary of each function follows on the next page.

      There are 54 functions in the WIL library.

      Also examine the usage of these functions in the example programs.




























     WIL4C Users Manual                                        Page 40

      +-------------------------------------------------------------------+
      | wilAccept : Accepts incoming connection.                          |
      | wilAttach : Attaches (initializes) winsock.                       |
      | wilAskHostByAddr : Request host information from server.          |
      | wilAskHostByName : Request host information from server.          |
      | wilAskProtoByName : Request protocol information.                 |
      | wilAskProtoByNumber : Request protocol information.               |
      | wilAskServByName : Request server information.                    |
      | wilAskServByPort : Request server information.                    |
      | wilAwaitEvent : Set asynchronous event winsock mask.              |
      | wilBind : Bind socket to specified address & port nunber.         |
      | wilCancelBlocking : Cancels blocking call.                        |
      | wilCloseSocket : Close socket.                                    |
      | wilConnect : Initiate connection to remote port.                  |
      | wilDataIsReady : Is socket readable (data is ready).              |
      | wilDebug : Returns bebug value.                                   |
      | wilErrorText : Get text associated with error code.               |
      | wilGetDescription : Get winsock description text.                 |
      | wilGetHostAddr : Get host address.                                |
      | wilGetHostAlias : Get host name alias.                            |
      | wilGetHostDotted : Get host dotted address.                       |
      | wilGetHostName : Get host name.                                   |
      | wilGetMaxSockets : Get maximum number of sockets supported.       |
      | wilGetMaxUDPSize : Get maximum UDP packet size.                   |
      | wilGetMyHostAddr : Get local host address.                        |
      | wilGetMyHostDotted : Get local host (dotted) address.             |
      | wilGetMyHostName : Get local host name.                           |
      | wilGetProtoName : Get protocol name.                              |
      | wilGetProtoNumber : Get protocol number.                          |
      | wilGetServName : Get server name.                                 |
      | wilGetServPort : Get server port.                                 |
      | wilGetSystemInfo : Get winsock system information.                |
      | wilGetVendorInfo : Get winsock vendor information.                |
      | wilIsBlocking : Is winsock currently blocking ?                   |
      | wilIsConnected : Is socket connected to remote ?                  |
      | wilIsDotted : Is dotted string properly formed ?                  |
      | wilListen : Listen for incoming connection attempts.              |
      | wilLocalSockAddr : Get local sock address for connected socket.   |
      | wilLocalSockPort : Get local sock port number for connected sock. |
      | wilParseDecimal : Parse decimal response code.                    |
      | wilPeekSocket : Peek into socket.                                 |
      | wilReadLine : Read line terminated with linefeed.                 |
      | wilReadOOB : Read Out-Of-Bound data.                              |
      | wilReadSocket : Read from socket.                                 |
      | wilReadString : Read string from socket.                          |
      | wilRelease : Release (free) winsock.                              |
      | wilRemoteSockAddr : Get remote sock address for connected socket. |
      | wilRemoteSockPort : Get remote port number for connected socket.  |
      | wilSetOOB : Sets Out-Of_Bound data state.                         |
      | wilSocketStatus : Get socket read/write status.                   |
      | wilTcpSocket : Create TCP socket.                                 |
      | wilWriteOOB : Write Out-Of_Bounds data to socket.                 |
      | wilWriteSocket : Write buffer to socket.                          |
      | wilWriteString : Write string to socket.                          |
      | wilWriteLine : Write linefeed terminated line to socket.          |
      +-------------------------------------------------------------------+


     WIL4C Users Manual                                        Page 41


      9.0 Other MarshallSoft Computing Products

      Several shareware products are available from MarshallSoft Computing.

      9.1 The Windows Standard Communications Library for C/C++

      The Windows Standard Communications Library for C/C++ (WSC4C) is a
      Windows based asynchronous serial communications library designed for
      software developers programming in C/C++. WSC4C uses the Windows
      communications driver. Both 16-bit amd 32-bit DLLs are included along
      with 5 example programs.

      The Windows Standard Communications Library for C/C++ (WSC4C) is
      available for $75 plus $6 S&H ($12 S&H overseas).

      9.2 The Personal Communications Library for Windows (C/C++)

      The Personal Communications Library for Windows (PCL4W) is a Windows
      based [Win16] asynchronous communications library designed for
      software developers programming in C/C++.  Unlike WSC4C, PCL4W
      interfaces to the serial port hardware directly.  PCL4W also supports
      multiport boards such as those made by DigiBoard and BOCA.

      The Personal Communications Library for Windows (PCL4W) is available
      for $75 plus $6 S&H ($12 S&H overseas).

      9.3 The Personal Communications Library for C/C++ / DOS

      PCL4C is similar to PCL4W except that it is designed for DOS.
      Includes support for both 16-bit and 32-bit protected mode.

      9.4 Libraries for Other Languages

      We have communications libraries for C/C++, Turbo Pascal, Visual
      Basic, and PowerBASIC. Check our BBS or WEB site.

       PCL4C  : C/C++, DOS [include 16-bit & 32-bit protected mode].
       PCL4P  : Turbo Pascal, DOS [includes 16-bit protected mode].
       PCL4VB : Visual Basic, DOS.
       PCL4PB : Power Basic, DOS.

        PCL4W : C/C++, Windows 3.1 & Win 95, talks to hardware directly.
       PCLVBW : Visual Basic, Win 3.1 & Win 95, talks to hardware directly.

        WSC4C : C/C++, Win 3.1, Win 95, Win NT. Uses Windows API.
       WSC4VB : Visual Basic, Win 3.1, Win 95, Win NT. Uses Windows API.
        WSC4D : Borland DELPHI, Win 3.1, Win 95, Win NT. Uses Windows API.










     WIL4C Users Manual                                        Page 42


